namespace RadioTimer.Services
{
    /// <summary>
    /// 时间报时服务接口
    /// 提供报时服务的核心功能，包括启动、停止服务和获取下次报时时间
    /// 通过定时器实现精准的时间检查和语音播报
    /// </summary>
    public interface ITimeChimeService
    {
        /// <summary>
        /// 获取服务是否正在运行的状态
        /// </summary>
        bool IsServiceRunning { get; }
        
        /// <summary>
        /// 报时触发事件
        /// 当成功执行报时时触发，传递报时的具体时间
        /// </summary>
        event EventHandler<DateTime>? ChimeTriggered;
        
        /// <summary>
        /// 服务状态变更事件
        /// 当服务状态发生变化时触发，传递状态描述信息
        /// </summary>
        event EventHandler<string>? ServiceStatusChanged;

        /// <summary>
        /// 异步启动报时服务
        /// 初始化定时器并开始定时检查报时条件
        /// </summary>
        /// <returns>异步任务</returns>
        Task StartServiceAsync();
        
        /// <summary>
        /// 异步停止报时服务
        /// 释放定时器资源并停止所有报时活动
        /// </summary>
        /// <returns>异步任务</returns>
        Task StopServiceAsync();
        
        /// <summary>
        /// 异步获取下一次报时的时间
        /// 根据当前设置计算下一个启用的报时时间点
        /// </summary>
        /// <returns>返回下一次报时的时间，如果没有启用的报时则返回null</returns>
        Task<DateTime?> GetNextChimeTimeAsync();
    }
}